home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / c-lang / vbcc.lha / readme.vbcc
Text File  |  1996-05-16  |  14KB  |  466 lines
  1.  
  2.  
  3. vbcc - portable ANSI C compiler (c) in 1995-96 by Volker Barthelmann
  4.  
  5.  
  6. INTRODUCTION
  7.  
  8.     vbcc is a free portable and retargetable ANSI C compiler.
  9.  
  10.     This archive contains the compiler, preprocessor, assembler, linker,
  11.     frontend, message browser, startup codes, C-libraries, amiga.lib
  12.     replacement as well as several other tools (mostly with complete source).
  13.  
  14.     This gives you a complete system that allows to develop programs in
  15.     ANSI C as well as Amiga-specific programs (provided you obtain the
  16.     OS-includes).
  17.  
  18.     All major parts of this distribution (including compiler, preprocessor,
  19.     libraries etc.) have been compiled/assembled with this system and
  20.     apart from the OS-includes everything is included to rebuilt vbcc,
  21.     the libraries and many of the other programs.
  22.  
  23.  
  24. FEATURES
  25.  
  26.     vbcc..
  27.  
  28.     - comes with source
  29.  
  30.     - is free
  31.  
  32.     - is portable and retargetable
  33.  
  34.     - comes with a global optimizer that can e.g. do global common
  35.       subexpression elimination, constant propagation, function inlining
  36.       and several other optimizations (but is not yet finished and stable)
  37.  
  38.     - should be (rather) ANSI compliant
  39.  
  40.     - can generate code that runs on a plain 68000 CPU
  41.  
  42.     - can generate code optimized for 020/030, 040 or 060
  43.  
  44.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  45.       and comes with appropriate math-libraries
  46.  
  47.     - generates standard Amiga object files
  48.  
  49.     - does not need too much memory
  50.  
  51.     - comes with a message browser
  52.  
  53.     - offers a lot of error/warning messages that can be turned on/off
  54.       separately
  55.  
  56.  
  57. WHAT'S NEW
  58.  
  59.     Some changes since the last release on Aminet:
  60.  
  61.     - lots of bug fixes
  62.  
  63.     - global optimizer
  64.  
  65.     - the distribution now contains everything needed and the installation
  66.       is easier
  67.  
  68.     - message browser
  69.  
  70.     - special math-library for 68040 (to be used together with some
  71.       replacement for the MathIeee-libraries) - probably a huge improvement
  72.       for 68060, too
  73.  
  74.     - the included vbcc executable has been compiled by itself and does not
  75.       need ixemul.library any more (saves time and memory)
  76.  
  77.     - more optional warnings
  78.  
  79.     - guide with all error/warning messages (converted by Walter Doerwald)
  80.  
  81.     - completed C library
  82.  
  83.  
  84. REQUIREMENTS
  85.  
  86.     To use vbcc you need:
  87.  
  88.     - an Amiga with OS 2.0 or higher (programs compiled with vbcc probably
  89.       work under earlier OS-versions, too)
  90.  
  91.     - enough RAM (it is probably possible to translate small programs with
  92.       1MB, but for larger programs much more will be needed)
  93.  
  94.     Stuff that is not needed, but may be very useful:
  95.  
  96.     - harddisk
  97.  
  98.     - editor
  99.  
  100.     - make, touch etc.
  101.  
  102.     - the Amiga OS-includes (they can be found on certain CDs and on
  103.       some ftp-servers which have those CDs mounted)
  104.  
  105.     - pipe-command (to use the message browser)
  106.  
  107.     Also you should know how to use the shell and you should know ANSI C
  108.     (if you need a book I recommend (like everyone) "The C Programming
  109.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  110.  
  111.  
  112. LEGAL
  113.  
  114.     Note that this distribution contains several programs, libraries etc.
  115.     that are from different authors and are under different legal status.
  116.     So always read the corresponding doc/guide-file to find out under
  117.     what conditions a certain file may be used, distributed etc.
  118.  
  119.     For the most part you can assume that you may use everything for
  120.     non-commercial purposes and may distribute the unchanged archive
  121.     in whole.
  122.  
  123.     Changing any parts from this archive, distributing parts of it or
  124.     using it commercially might be legal for certain parts, but illegal
  125.     for others, so read all docs carefully before doing any of the above.
  126.  
  127.     This archive contains code written by (this list may be incomplete):
  128.  
  129.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  130.     Matthias Fleischer, Gunther Nikl, Mike Schwartz
  131.  
  132.     However, if you have any comments/problems etc. with anything, please
  133.     do not bother them, but write to me (volker@vb.franken.de) first.
  134.  
  135.  
  136. INSTALLATION/TUTORIAL
  137.  
  138.     The first step (which you probably already did) is to extract the
  139.     entire archive (take care to preserve the file attributes).
  140.  
  141.     The distributed programs are for the most part only usable from a shell.
  142.  
  143.     To use vbcc the following steps are necessary:
  144.  
  145.     1. Assign vbcc: to the subdirectory vbcc/machines/amiga68k.
  146.  
  147.     2. Assign vlib: to vbcc:lib.
  148.  
  149.     3. Assign vinclude: to vbcc:include.
  150.  
  151.        If you have the OS-includes you can either add the path to this
  152.        assign, e.g.
  153.  
  154.         assign vinclude: vbcc:include myhd:os-includes
  155.  
  156.        or you can modify the vc.config (see below).
  157.  
  158.     4. Add vbcc:bin to your path.
  159.  
  160.     5. set the stack to a reasonable value (perhaps some 10k).
  161.  
  162.     If you use vbcc frequently it is probably a good idea to add those
  163.     commands to your user-startup, shell-startup or similar.
  164.     However if you just want to try it out the sample script init_vbcc in
  165.     the subdirectory machines/amiga68k does all this for you.
  166.     You have to cd in its directory and start it from there, e.g.:
  167.  
  168.         cd myhd:vbcc/machines/amiga68k
  169.         init_vbcc
  170.  
  171.     Now you should be able to use vbcc. E.g. if you want to compile and
  172.     link the program hello.c you can type
  173.  
  174.         vc hello.c
  175.  
  176.     This will compile and link the file hello.c and create the executable
  177.     a.out in the current directory.
  178.  
  179.         vc hello.c -o hello
  180.  
  181.     will do the same, but the created executable will be called hello.
  182.  
  183.         vc -c t1.c t2.c
  184.  
  185.     will compile t1.c and t2.c without linking, creating the object files
  186.     t1.o and t2.o.
  187.  
  188.         vc t1.o t2.o -o tt
  189.  
  190.     will link them together and create the executable tt.
  191.  
  192.     If your program uses floating point add -lmieee to the commandline
  193.     to link with the math-library, e.g.:
  194.  
  195.         vc calc.c -o calc -lmieee
  196.  
  197.     For further information read the files:
  198.  
  199.         vbcc/doc/vbcc.doc
  200.         vbcc/machines/amiga68k/doc/vc.doc
  201.         vbcc/machines/amiga68k/doc/vbccamiga68k.doc
  202.         vbcc/machines/amiga68k/doc/vclib.doc
  203.  
  204.  
  205. CONFIGURATION
  206.  
  207.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  208.     preferences. The provided sample vc.config should be usable and does
  209.     not have to be changed but you can add something to suit your personal
  210.     preferences - read
  211.  
  212.         vbcc/machines/amiga68k/doc/vc.doc
  213.  
  214.     to find out more.
  215.  
  216.     If you have the OS-includes and do not want to add them to the vinclude:
  217.     assign mentioned above you can also modify the vc.config file:
  218.  
  219.     Add -I<full_path> directly after the two occurences of -Ivinclude: in
  220.     the sample vc.config, e.g.:
  221.  
  222.         -pp=vcpp -Ivinclude: -Imyhd:os-include -D__STDC__=1 %s >%s
  223.         -ppv=vcpp -Ivinclude: -Imyhd/os-include -D__STDC__=1 %s >%s
  224.  
  225.  
  226.     There is a smaller version of vbcc which does not contain the optimizer.
  227.     If you do not intend to use the optimizer or have tight memory you can
  228.     rename vbcc/machines/amiga68k/bin/vbcc to vbccl and rename
  229.     vbcc/machines/amiga68k/bin/vbccs to vbcc. This will save some memory.
  230.  
  231.  
  232. MESSAGE BROWSER
  233.  
  234.     If you start the message browser with
  235.  
  236.         run vbrowse
  237.  
  238.     it will open a window with a listview gadget. If you have a pipe
  239.     command installed you can now invoke vc via tovbr, e.g.
  240.  
  241.         tovbr vc hello.c
  242.  
  243.     and any output from vc will be displayed in the window of vbrowse
  244.     rather than in the shell. It might be convenient to make an alias like
  245.  
  246.         alias vb tovbr vc
  247.  
  248.     so that invoking vb will automatically display the output in the browser.
  249.  
  250.     If there is an error/warning-message in the browser you can invoke a
  251.     configurable command by double-clicking on the message.
  252.  
  253.     Double-clicking on the quoted line will invoke GoldEd (if you have it
  254.     installed) by default, load the file that caused the error and the cursor
  255.     will be placed on this line in the default configuration. If you use
  256.     another editor or want to change this behaviour have a look at
  257.     vbcc/machines/amiga68k/doc/vbrowse.doc.
  258.  
  259.     Double-clicking on the error-line (the one below the quoted line) will
  260.     invoke the command showerr that will open the VBCCMessages.guide and
  261.     display a more detailed description of the error (if there is one in
  262.     the guide - there are not yet descriptions for all messages).
  263.  
  264.     Read vbcc/machines/amiga68k/vbrowse.doc for further information.
  265.  
  266.  
  267. CONTENTS
  268.  
  269.     This archive contains (among others) the following files and directories:
  270.  
  271.     vbcc/
  272.  
  273.             The main directory. The source files for the compiler and the
  274.             builtin preprocessor by Thorsten Schaaps are here.
  275.  
  276.     vbcc/doc/
  277.  
  278.             Target independant documentation for the compiler is in this dir.
  279.  
  280.     vbcc/doc/History
  281.  
  282.             Changes in since earlier versions of the compiler.
  283.  
  284.     vbcc/doc/vbcc.doc
  285.  
  286.             Documentation for the target-independant part of the compiler.
  287.  
  288.     vbcc/doc/errors.doc
  289.  
  290.             A list of all error/warning-messages from the compiler -
  291.             sometimes with more detailed descriptions.
  292.  
  293.     vbcc/machines/amiga68k/
  294.  
  295.             Everything that is specific to the Amiga68k is in this directory.
  296.  
  297.     vbcc/machines/amiga68k/doc/
  298.  
  299.             This contains documentation for the Amiga68k specific parts.
  300.  
  301.     vbcc/machines/amiga68k/doc/PhxAss.guide
  302.  
  303.             Documentation for the assembler by Frank Wille. Note that this
  304.             distribution only contains FreePhxAss and that there is another
  305.             version that is shareware.
  306.  
  307.     vbcc/machines/amiga68k/doc/PhxLnk.guide
  308.  
  309.             Documentation for the linker by Frank Wille.
  310.  
  311.     vbcc/machines/amiga68k/doc/VBCCMessages.guide
  312.  
  313.             The vbcc/doc/errors.doc in Amigaguide-format (done by Walter
  314.             Doerwald).
  315.  
  316.     vbcc/machines/amiga68k/doc/vbccamiga68k.doc
  317.  
  318.             Amiga68k-specific documentation for the compiler.
  319.  
  320.     vbcc/machines/amiga68k/doc/vc.doc
  321.  
  322.             Documentation for the Amiga-compiler-frontend.
  323.  
  324.     vbcc/machines/amiga68k/doc/vclib.doc
  325.  
  326.             Documentation for the Amiga-C-library.
  327.  
  328.     vbcc/machines/amiga68k/doc/vcpp.doc
  329.  
  330.             Some short comments regarding the preprocessor from the
  331.             lcc-distribution. Read the copyright-notice.
  332.  
  333.     vbcc/machines/amiga68k/doc/vbrowse.doc
  334.  
  335.             Documentation on the message browser and several connected tools.
  336.  
  337.     vbcc/machines/amiga68k/doc/fd2lib.doc
  338.  
  339.             Documentation for fd2lib.
  340.  
  341.     vbcc/machines/amiga68k/doc/minstart.doc
  342.  
  343.             Documentation for minstart.o.
  344.  
  345.     vbcc/machines/amiga68k/doc/alib.doc
  346.  
  347.             Documentation for alib by Mike Schwartz.
  348.  
  349.     vbcc/machines/amiga68k/init_vbcc
  350.  
  351.             A sample script to do the necessary assigns etc. to use vbcc.
  352.  
  353.     vbcc/machines/amiga68k/include
  354.  
  355.             This directory contains the standard-ANSI-includes for vbcc.
  356.  
  357.     vbcc/machines/amiga68k/bin/
  358.  
  359.             This directory contains all executables.
  360.  
  361.     vbcc/machines/amiga68k/bin/vbcc
  362.  
  363.             The C compiler with global optimizer.
  364.  
  365.     vbcc/machines/amiga68k/bin/vbccs
  366.  
  367.             A smaller version of the C compiler without optimizer.
  368.  
  369.     vbcc/machines/amiga68k/bin/vc
  370.  
  371.             The compiler-frontend.
  372.  
  373.     vbcc/machines/amiga68k/bin/vcpp
  374.  
  375.             The preprocessor from the lcc-distribution (by Dennis Ritchie).
  376.  
  377.     vbcc/machines/amiga68k/bin/FreePhxAss
  378.  
  379.             The assembler by Frank Wille.
  380.  
  381.     vbcc/machines/amiga68k/bin/PhxLnk
  382.  
  383.             The linker by Frank Wille.
  384.  
  385.     vbcc/machines/amiga68k/bin/vbrowse
  386.     vbcc/machines/amiga68k/bin/vsend
  387.     vbcc/machines/amiga68k/bin/tovbr
  388.     vbcc/machines/amiga68k/bin/showerr
  389.  
  390.             The message browser and some tools.
  391.  
  392.     vbcc/machines/amiga68k/bin/fd2lib
  393.  
  394.             fd2lib generates stubs for shared libraries and must used to
  395.             rebuilt amiga.lib or if you want to use any custom shared-library.
  396.  
  397.     vbcc/machines/amiga68k/bin/alib
  398.  
  399.             Used to create link-libraries.
  400.  
  401.     vbcc/machines/amiga68k/lib/
  402.  
  403.             This directory contains the link-libraries and startup-codes.
  404.  
  405.     vbcc/machines/amiga68k/lib/startup.o
  406.  
  407.             The standard startup-code.
  408.  
  409.     vbcc/machines/amiga68k/lib/vc.lib
  410.  
  411.             The standard C-library.
  412.  
  413.     vbcc/machines/amiga68k/lib/vcs.lib
  414.  
  415.             The small data C-library.
  416.  
  417.     vbcc/machines/amiga68k/lib/mieee.lib
  418.  
  419.             Math-library that uses the MathIeee-libraries.
  420.  
  421.     vbcc/machines/amiga68k/lib/m881.lib
  422.  
  423.             Math-library that uses FPU-instructions of the 68881/2.
  424.  
  425.     vbcc/machines/amiga68k/lib/m040.lib
  426.  
  427.             Math-library that uses FPU-instructions that do not have to be
  428.             emulated on a 68040 and the MathIeee-libraries for other
  429.             functions.
  430.  
  431.     vbcc/machines/amiga68k/lib/amiga.lib
  432.  
  433.             Replacement for the standard amiga.lib.
  434.  
  435.     vbcc/machines/amiga68k/lib/amigas.lib
  436.  
  437.             Small data replacement for the standard amiga.lib.
  438.  
  439.     vbcc/machines/amiga68k/lib/minstart.o
  440.  
  441.             Small startup-code for small programs that do not use functions
  442.             from the C-library.
  443.  
  444.  
  445. BUGREPORTS/COMMENTS
  446.  
  447.     If you think vbcc generates bad code, throws enforcer hits, crashes,
  448.     seems to be not ANSI-compliant etc. and the problem is not mentioned
  449.     anywhere in this docs as known problem, please send a mail with your
  450.     system configuration, the vbcc version, the command line you used, the
  451.     source that caused the problem and a brief description of the problem to
  452.  
  453.         volker@vb.franken.de
  454.  
  455.     Also if you find problems with the includes, the libraries or you have
  456.     suggestions, dislikes etc. send me a mail.
  457.     Corrections, improvements etc. of the manuals are appreciated, too.
  458.  
  459.  
  460.  
  461. Volker Barthelmann                                      volker@vb.franken.de
  462. Kennedy-Ring 39
  463. 91301 Forchheim
  464. Germany
  465.  
  466.